package com.example.musicaiap.ui.home

import com.example.musicaiap.mvi.base.UiEffect
import com.example.musicaiap.mvi.base.UiIntent
import com.example.musicaiap.mvi.base.UiState
import com.example.musicaiap.domain.model.Playlist
import com.example.musicaiap.domain.model.Song

/**
 * 主页的MVI契约
 * 定义了主页UI的状态(State)、用户意图(Intent)和UI效应(Effect)
 * 遵循MVI架构模式，实现单向数据流
 */
object HomeContract {
    
    /**
     * 主页UI状态
     * 包含显示首页所需的所有数据
     */
    data class State(
        // Removed: isLoading, error, recommendSongs, playlists, isLocalMusicSelected
        val currentPlayingSong: Song? = null,         // 当前正在播放的歌曲
        val isPlayerVisible: Boolean = false,         // 是否显示迷你播放器 (可能仍用于控制MiniPlayer显隐)
        val isPlaying: Boolean = false,               // 是否正在播放
        val currentPosition: Long = 0,                // 当前播放位置（毫秒）
        val duration: Long = 0,                       // 当前歌曲总时长（毫秒）
        val localSongs: List<Song> = emptyList(),     // 本地扫描到的歌曲列表 (用于LibraryScreen)
        val isScanningLocalMusic: Boolean = false,    // 是否正在扫描本地音乐 (用于LibraryScreen)
        val localMusicError: String? = null,          // 本地音乐扫描错误信息 (用于LibraryScreen)
        val recentHistory: List<Song> = emptyList(),   // 最近播放历史 (可能未来使用)
        val currentPlaylist: List<Song> = emptyList()  // 用于MiniPlayer的播放列表按钮
    ) : UiState

    /**
     * 主页意图
     * 代表用户可以在主页执行的所有操作
     */
    sealed interface Intent : UiIntent {
        // 页面加载
        /**
         * 加载首页内容
         * 当页面首次显示或需要刷新时触发
         */
        object LoadContent : Intent
        
        // 点击歌曲
        /**
         * 点击歌曲意图
         * 当用户点击歌曲列表项时触发，用于播放该歌曲
         * @param song 被点击的歌曲
         */
        data class ClickSong(val song: Song) : Intent

        // Removed: ClickPlaylist Intent

        // 播放控制
        /**
         * 切换播放/暂停意图
         * 当用户点击播放/暂停按钮时触发
         */
        object TogglePlayPause : Intent
        
        /**
         * 下一首歌曲意图
         * 当用户点击下一首按钮时触发
         */
        object NextSong : Intent
        
        /**
         * 上一首歌曲意图
         * 当用户点击上一首按钮时触发
         */
        object PreviousSong : Intent
        
        /**
         * 跳转到指定播放位置
         * 当用户拖动进度条时触发
         * @param position 目标播放位置(毫秒)
         */
        data class SeekTo(val position: Long) : Intent
        
        // 点击迷你播放器
        /**
         * 点击迷你播放器意图
         * 当用户点击底部迷你播放器区域时触发，用于导航到播放器全屏页面
         */
        object ClickMiniPlayer : Intent
        
        // 本地音乐相关
        /**
         * 扫描本地音乐意图
         * 当用户点击"扫描"按钮时触发，开始扫描设备上的音乐文件
         */
        object ScanLocalMusic : Intent

        // Removed: SelectLocalMusicTab Intent
        // Removed: SelectHomeTab Intent

        // 权限结果
        /**
         * 权限结果意图
         * 当权限请求结果返回时触发
         * @param granted 权限是否被授予
         */
        data class PermissionResult(val granted: Boolean) : Intent
    }
    
    /**
     * 主页效应
     * 代表由ViewModel向UI层发送的一次性事件
     */
    sealed interface Effect : UiEffect {
        // 导航到播放列表详情
        /**
         * 导航到播放列表详情效应
         * 当需要跳转到播放列表详情页面时发送
         * @param playlistId 要查看的播放列表ID
         */
        data class NavigateToPlaylist(val playlistId: String) : Effect
        
        // 显示消息
        /**
         * 显示Toast消息效应
         * 当需要显示提示消息时发送
         * @param message 要显示的消息文本
         */
        data class ShowToast(val message: String) : Effect
        
        // 导航到播放器屏幕
        /**
         * 导航到播放器页面效应
         * 当需要跳转到全屏播放器页面时发送
         */
        object NavigateToPlayer : Effect
        
        // 权限相关
        /**
         * 请求存储权限效应
         * 当需要访问本地音乐时发送，用于请求存储权限
         */
        object RequestStoragePermission : Effect
    }
}
